captureReservation

HTTP method: POST

When payment funds have been reserved and the goods are ready for delivery, your system should call the capture API call to capture the payment.

Capture is not possible for payments with expired authorization. If you attempt to submit a capture request for a payment with a reserved amount after the authorization expiry date has passed, the request will fail.
The authorizationExpiryDate can be found under the transaction section in the API Payment Response. Note that only certain payment methods have an expiration for authorization.
Please ensure you monitor the expiration date and avoid requesting capture for expired reservations.

Select a payment method to see the parameters relevant for that method:

Request parameters

You cannot capture more than the full amount.

Parameter

Description

Type

Mandatory

amount

This is the gross amount to be captured (including taxes).

If you do not want to capture the full amount, a smaller amount can be captured.

The amount must be greater than 0.00, and equal to, or lower than the reserved amount.

Partial captures are not supported when integrating with MobilePay Subscriptions.

float

Yes

invoice_number

The invoice number as it appears on the invoice.

String

orderLine

Listing of order lines.

Array
See table below

Yes

Recommended for all acquirers

reconciliation_identifier

This is the sales reconciliation identifier, used in the reconciliation CSV files you can download from the Merchant Interface, or by using the getCustomReport method. For more information, see getCustomReport.

String{0,100}

sales_tax

The sales tax amount. Indicates how much of the gross amount that was sales tax, e.g. VAT (UK) or Moms (DK).

float

trackingInfo[]

Tracking information, in an array. Could include:

trackingId	Id of the tracking. Maximum 100 characters.
refTrackingId	Id of the referred tracking. Maximum 100 characters. Used to identify the related tracking. For Klarna Payments this can be used to link the return tracking to the shipping tracking.
companyName	Name of the shipping company. Maximum 100 characters. You are advised to be as specific as possible, including the region/branch, etc where appropriate
method	Allowed values matches (PickUpStore\|Home\|BoxReg\|BoxUnreg\|PickUpPoint\|Own)
trackingNumber	Tracking number for the shipment. Maximum 100 characters
trackingUri	URL where the customer can track their shipment. Maximum 1024 characters
type	Type of the tracking information. Possible values: SHIPPING, RETURN

trackingInfo[0][trackingId] = 1
trackingInfo[0][companyName] = Mærsk
trackingInfo[0][method] = PickUpStore
trackingInfo[0][trackingNumber] = 123abc
trackingInfo[0][trackingUri] = www.tracking.com/id
trackingInfo[0][type] = SHIPPING
trackingInfo[1][trackingId] = 2
trackingInfo[1][refTrackingId] = 1
trackingInfo[1][companyName] = ReturnCo
trackingInfo[1][trackingNumber] = 456abc
trackingInfo[1][trackingUri] = www.tracking.com/id2
trackingInfo[1][type] = RETURN

See https://docs.klarna.com/api/ordermanagement/#operation/captureOrder

Please make sure you passed same number of tracking info of SHIPPING type with the RETURN type so that it can be mapped correctly with the KlarnaPayments shipping_info

Array

Optional but recommended

transaction_id

The id of a specific payment.

[0-9a-f]{1,32}

Yes

To partially capture reservations for Klarna KP, Santander, or (Arvato) PayByBill, you must include the captured order lines:

Parameter	Description	Type	Mandatory
orderLines	The individual line items of the order. This is mandatory for some providers, and recommended for a good customer experience.	Array	Yes

Value	Description	Type	Mandatory
description	Description of an item.	String (255)	Yes
itemId	The item identification. Each itemId must be unique within an order.	String (100)	Yes
quantity	The quantity of the item. The value must be greater than zero.	Decimal	Yes
unitPrice	The unit price, excluding sales tax. The value must be greater than zero, unless the optional goodsType parameter is set to handling, in which case the field can be used to provide a discount.	Decimal	Yes
taxPercent	This is the tax percentage of the unit price. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one, the other is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.	Decimal	No
taxAmount	This is the total tax on an order line, before any discounts are applied. It is recommended to use taxAmount if possible. If you provide both taxPercent and taxAmount, the amount takes precedence. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one of the taxPercent and taxAmount parameters, the other parameter is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.	Decimal	Yes
unitCode	The relevant measurement unit for the order line. For example, kg.	String (50)
discount	The order line's discount in percent.	Decimal
goodsType	The goods type of the order line - shipment \| handling \| item \| digital \| discount \| gift_card \| physical \| sales_tax
imageUrl	The full URL of the icon for the item	String (255)
productUrl	The full URL for the description of the item	String (255)

Response parameters

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).

Value	Description
CaptureAmount	The amount that was captured.
CaptureCurrency	The currency of the capture.
Result	The result of the request, for example: Success Fail Open PartialSuccess Error. The MerchantErrorMessage and CardHolderErrorMessage elements show more information about the error.
Transactions	Contains a set of Transaction elements, each describing the relevant transactions. For more information, see Transaction.

Examples

Basic request

curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/captureReservation \
  --header 'Authorization: Basic auth' \
  --data transaction_id=12345 \
  --data amount=50.20 \

Request with orderLines

curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/captureReservation \
  --header 'Authorization: Basic auth' \
  --data transaction_id=12345 \
  --data amount=14.20 \
  --data orderLines[0][description]='White sugar' \
  --data orderLines[0][itemId]=productid \
  --data orderLines[0][quantity]=1.5 \
  --data orderLines[0][taxPercent]=20 \
  --data orderLines[0][unitCode]=kg \
  --data orderLines[0][unitPrice]=5.75 \
  --data orderLines[1][description]='Brown sugar' \
  --data orderLines[1][itemId]=productid2 \
  --data orderLines[1][quantity]=2.5 \
  --data orderLines[1][taxPercent]=20 \
  --data orderLines[1][unitCode]=kg \
  --data orderLines[1][unitPrice]=8.75 \

XML response

<?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-09-29T12:34:56+02:00</Date>
		<Path>API/captureReservation</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<CaptureAmount>0.20</CaptureAmount>
		<CaptureCurrency>978</CaptureCurrency>
		<Result>Success</Result>
		<CaptureResult>Success</CaptureResult> <!-- deprecated -->
		<Transactions>
			<Transaction>
				<TransactionId>1</TransactionId>
				<PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId>
				<AuthType>payment</AuthType>
				<CardStatus>Valid</CardStatus>
				<CreditCardExpiry>
					<Year>2028</Year>
					<Month>08</Month>
				</CreditCardExpiry>
				<CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2
				</CreditCardToken>
				<CreditCardMaskedPan>411111******1111</CreditCardMaskedPan>
				<CardInformation>
					<IsTokenized>false</IsTokenized>
					<Token>hYKu5yO33OsWYfT7g4weghvPjBnb3YEZYDysb7NzAf/sHk7j5j5ejzfF2ZyhLyggcCgaNKEmjg==+1</Token>
					<MaskedPan>411111******1111</MaskedPan>
					<Expiry>
						<Year>2028</Year>
						<Month>08</Month>
					</Expiry>
					<IssuingCountry>DK</IssuingCountry>
					<LastFourDigits>1111</LastFourDigits>
					<Scheme>VISA</Scheme>
				</CardInformation>
				<ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
				<InvoiceOrderInfo />
				<LiableForChargeback>Merchant</LiableForChargeback>
				<BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e
				</BlacklistToken>
				<ShopOrderId>myorderid</ShopOrderId>
				<Shop>AltaPay Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>captured</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>1.00</ReservedAmount>
				<CapturedAmount>1.00</CapturedAmount>
				<RefundedAmount>0</RefundedAmount>
				<RecurringDefaultAmount>0</RecurringDefaultAmount>
				<CreatedDate>2010-09-28 12:34:56</CreatedDate>
				<UpdatedDate>2010-09-28 12:34:56</UpdatedDate>
				<PaymentNature>CreditCard</PaymentNature>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>false</SupportsMultipleRefunds>
				</PaymentNatureService>
				<FraudRiskScore>13.37</FraudRiskScore>
				<FraudExplanation>Fraud detection explanation</FraudExplanation>
				<PaymentInfos>
					<PaymentInfo name="Form_Created_At">2010-09-28 12:34:56</PaymentInfo>
					<PaymentInfo name="Form_Provider">AltaPay Test Form</PaymentInfo>
					<PaymentInfo name="Merchant_Provided_Info">Some info by merchant</PaymentInfo>
				</PaymentInfos>
				<CustomerInfo>
					<UserAgent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.7
				(KHTML, like Gecko) Chrome/16.0.912.41 Safari/535.7</UserAgent>
					<IpAddress>127.127.127.127</IpAddress>
					<Email>support@altapay.com</Email>
					<Username>support</Username>
					<CustomerPhone>+45 7020 0056</CustomerPhone>
					<OrganisationNumber>12345678</OrganisationNumber>
					<CountryOfOrigin>
						<Country>DK</Country>
						<Source>BillingAddress</Source>
					</CountryOfOrigin>
					<BillingAddress>
						<Firstname>Palle</Firstname>
						<Lastname>Simonsen</Lastname>
						<Address>Rosenkæret 13</Address>
						<City>Søborg</City>
						<PostalCode>2860</PostalCode>
						<Country>DK</Country>
					</BillingAddress>
					<ShippingAddress />
					<RegisteredAddress />
				</CustomerInfo>
				<ReconciliationIdentifiers>
					<ReconciliationIdentifier>
						<Id>f4e2533e-c578-4383-b075-bc8a6866784a</Id>
						<Amount currency="978">1.00</Amount>
						<Type>captured</Type>
						<Date>2020-09-28T12:00:00+02:00</Date>
					</ReconciliationIdentifier>
				</ReconciliationIdentifiers>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse

Test case data

Use the following to test credit card transactions.

Scenario	Error type	Amount	Card Number
Fails at captureReservation	Failed	7.66	Pattern: ????????????0766 Visa: 4170000000000766 MasterCard: 5540000000000766
Fails at captureReservation	Error	7.67	Pattern: ????????????0767 Visa: 4120000000000767 MasterCard: 5580000000000767
Triggered at captureReservation	20 second delay	19.66	Pattern: ????????????1966 Visa: 4150000000001966 MasterCard: 5520000000001966
Triggered at captureReservation ( To create the chargeback object, capture the reservation, then go to the Merchant Information Interface, and under Home > Terminal Settings, click on Create test reconciliation data)	Chargeback	19.67	Pattern: ????????????1967 Visa: 4150000000001967 MasterCard: 5520000000001967

Test URL	https://testgateway.altapaysecure.com/merchant/API/<method>
Production URL	https://<YourShopName>.altapaysecure.com/merchant/API/<method>